.\" Process this file with
.\" nroff -e -mandoc foo.1
.\"
.TH yangdump 1 "February 6, 2012" Linux "yangdump 2.2"
.SH NAME
yangdump \- validate YANG modules and convert them to different formats

.SH SYNOPSIS
.nf

   yangdump (module=value | subtree=value)+ [parameter=value...]

   yangdump  --help [brief | normal | full]

   yangdump  --version

   yangdump  --show-errors

.fi
.SH DESCRIPTION
.B yangdump
provides validation and translation of YANG data models.
Information about a module or submodule can be generated as well.
This version of yangdump supports the YANG data modeling language
defined in \fBRFC 6020\fP.

The \fBformat\fP parameter is used to select a translation output mode.
If it is missing, then no translation will be done.

This parameter can be used with the module reports parameters,
but the translation output should be directed to a file
instead of STDOUT to keep them separated.

For XSD 1.0 translation, use the \fBformat=xsd\fP parameter.

For XHTML 1.0 translation, use the \fBformat=html\fP parameter.
    
For a 1 line output of the module name and version,
use the \fBmodversion\fP parameter.
    
For a listing of all the symbols that the file exports
to other files, use the \fBexports\fP parameter.
    
For a listing of all the files that the file depends on,
to compile, use the \fBdependencies\fP parameter.
    
For a listing of all the accessible object identifiers that
the file contains, use the \fBidentifiers\fP parameter.

For a listing of all the accessible object identifiers that
the file contains, in tree format, use the \fBtree-identifiers\fP 
parameter.

.SH USAGE
Parameters can be entered in any order, and have the form:

   \fB[start] name [separator [value]]\fP

where:

    \fBstart\fP == 0, 1, or 2 dashes (foo, -foo, --foo)

    \fBname\fP == parameter name
.nf

         Parameter name completion will be attempted 
         if a partial name is entered.

.fi
    \fBseparator\fP == whitespace or equals sign (foo=bar, foo bar)

    \fBvalue\fP == string value for the parameter.
.nf

         Strings with whitespace need to be double quoted 
         (--foo="some string")

.fi
Some examples of valid command line parameters:
.nf

   foo=3
   -foo=3
   --foo=3
   foo 3
   foo=fred
   --foo "fred flintstone"
.fi

Partial parameter names can be entered if they are unique.

.SH OPTIONS
.IP --\fBconfig\fP=filespec
The name of the configuration file to use.
Any parameter except this one can be set in the config file.
The default config file 
.I /etc/yuma/yangdump.conf
will be not be checked if this parameter is present.
.IP --\fBdefnames\fP=boolean
If true, output to a file with the default name for the format,
in the current directory. The default value is 'false'.

If the \fBoutput\fP parameter is present and represents
an existing directory, then the default filename
will be created in that directory, instead of the
current directory.
.IP --\fBdependencies\fP
Validate the file, write the module name, version 
and module source for each file that this [sub]module
imports and includes, then exit.
        
Each dependency type, name, version, and source
is listed once. 
        
If the dependency version and source are missing,
then that import or include file was not found.
.IP --\fBdeviation\fP=string
 This parameter identifies a YANG module that
should only be checked for deviation statements
for external modules.  These will be collected
and applied to the real module(s) being processed.
       
Deviations are applied as patches to the target module.
Since they are not identified in the target module at
all (ala imports), they have to be specified
explicitly, so they will be correctly processed.
Zero or more instances of this parameter are allowed.
.IP --\fBexports\fP
Validate the file, write information for the symbols
that this [sub]module exports, then exit.  Report
includes the following info for the specific file,
not the entire module, if submodules are used:
.nf

   - [sub]module name
   - version
   - source filespec
   - namespace (module only)
   - prefix (module only)
   - belongs-to (submodule only)
   - typedefs
   - groupings
   - objects, rpcs, notifications
   - extensions.

.fi
.IP --\fBfeature-code-default\fP=enum
If 'dynamic' (the default), then dynamic SIL feature code
will be generated by default.
If 'static', then static SIL feature code
will be generated by default.
If false, then features will be disabled by default.
.IP --\fBfeature-disable\fP=module:feature
Identifies a feature which should be considered disabled.
.IP --\fBfeature-dynamic\fP=module:feature
Identifies a dynamic feature for SIL code generation purposes.
Zero or more entries are allowed.
.IP --\fBfeature-enable-default\fP=boolean
If true (the default), then features will be enabled by default.
If false, then features will be disabled by default.
.IP --\fBfeature-enable\fP=module:feature
Identifies a feature which should be considered enabled.
Zero or more entries are allowed.
.IP --\fBfeature-static\fP=module:feature
Identifies a static feature for SIL code generation purposes.
Zero or more entries are allowed.
.IP --\fBformat\fP=string
Type of conversion desired, if any. If this
parameter is missing, then no translation
will be done, but the module will be validated,
and any requested reports will be generated.

The following translation formats are available:

.nf

    xsd:  XSD 1.0 
   html:  XHTML 1.0
   yang:  Canonical YANG (in progress)
   copy:  Validate, and copy with a new name
    yin:  YIN format
      c:  Combined Yuma and User SIL C module
      h:  Combined Yuma and User SIL H file
     uc:  User part of a split SIL C module
     uh:  User part of a split SIL H file
     yc:  Yuma part of a split SIL C module
     yh:  Yuma part of a split SIL H file

.fi
.IP --\fBhelp\fP
Print this help text and exit.
The help-mode choice (--brief, --normal, or --full) may also be present
to control the amount of help text printed.
.IP --\fBhome\fP=dirspec
Directory specification for the home directory
to use instead of HOME.
.IP --\fBhtml-div\fP
If HTML translation is requested, then this parameter will
cause the output to be a single <div> element, instead of
an entire HTML file.  This allows the HTML translation
to be easily integrated within more complex WEB pages,
but the proper CSS definitions need to be present for the 
HTML to render properly. 

The default filename extension will be '.div' instead of '.html'
if this parameter is present.  The contents will be well-formed
XHTML 1.0, but without any namespace declarations.
.IP --\fBhtml-toc\fP=string
The HTML Table of Contents output mode.
Ignored unless the \fBformat\fP parameter is
set to \fBhtml\fP.  Default is \fBmenu\fP.

Values:
.nf

   - none: no ToC generated
   - plain: plain list ToC generated
   - menu: drop-down menu ToC generated.

.fi
.IP --\fBidentifiers\fP
Validate the file, write the list of object identifiers,
that this [sub]module contains, then exit.
        
Each accessible object node is listed once,
including all child nodes.  Notifications and
RPC methods are considered top-level objects,
and have object identifiers as well as configuration
and state data..
.IP --\fBindent\fP=number
Number of spaces to indent (0..9) in formatted output.
The default is 2 spaces.
.IP --\fBlog\fP=filespec
Filespec for the log file to use instead of STDOUT.
If this string begins with a '~' character,
then a username is expected to follow or
a directory separator character.  If it begins
with a '$' character, then an environment variable
name is expected to follow.
.IP --\fBlog-append\fP
If present, the log will be appended not over-written.
If not, the log will be over-written.
Only meaningful if the \fBlog\fP parameter is
also present.
.IP --\fBlog-level\fP=enum
Sets the debug logging level for the program.
.IP --\fBmodpath\fP=list
Directory search path for YANG and YIN files.
Overrides the YUMA_MODPATH environment variable.
.IP --\fBmodule\fP=string
YANG or YIN source module name to validate and convert.

If this string represents a filespec, 
ending with the \fB.yang\fP or \fB.yin\fP extension,
then only that file location will be checked.

If this string represents a module name, then
the module search path will be checked for
a file the \fB.yang\fP or \fB.yin\fP extension.

If this string begins with a '~' character,
then a username is expected to follow or
a directory separator character.  If it begins
with a '$' character, then an environment variable
name is expected to follow.
.nf

      ~/some/path ==> <my-home-dir>/some/path

      ~fred/some/path ==> <fred-home-dir>/some/path

      $workdir/some/path ==> <workdir-env-var>/some/path
.fi
.IP --\fBmodversion\fP
Validate the file, write the [sub]module 
name, version and source filespec, then exit.
.IP --\fBobjview\fP=string
Determines how objects are generated in HTML and YANG outputs.
The default mode is the \fBraw\fP view.
XSD output is always \fBcooked\fP, since refined groupings
and locally-scoped definitions are not supported in XSD.
Values:
.nf

   raw -- output includes augment and uses clauses, not the
          expanded results of those clauses.
  
   cooked -- output does not include augment or uses clauses,
            just the objects generated from those clauses.
.fi
.IP --\fBoutput\fP=filespec
Output file name to use. 
Default is STDOUT if none specified and the
\fBdefname\fP parameter is also missing.

If this parameter represents an existing directory,
then the \fBdefnames\fP parameter will be assumed by
default, and the translation output file(s) will be
generated in the specified directory.

If this parameter represents a file name,
then the \fBdefnames\fP parameter will be ignored,
and all translation output will be directed
to the specified file.

If this string begins with a '~' character,
then a username is expected to follow or
a directory separator character.  If it begins
with a '$' character, then an environment variable
name is expected to follow.
.nf

      ~/some/path ==> <my-home-dir>/some/path

      ~fred/some/path ==> <fred-home-dir>/some/path

      $workdir/some/path ==> <workdir-env-var>/some/path

.fi
.IP --\fBshow-errors\fP
If present, list each error or warning 
number and its default message string.
The program will exit after this is done.
.IP --\fBsimurls\fP=boolean
If true, and if HTML translation is requested, then this parameter will
cause the format of URLs within links to be generated
in simplified form, for WEB development engines such
as CherryPy, which support this format.
The default is false.
.nf

   Normal URL format:
     example.html?parm1=foo&parm2=bar#frag

   Simplified URL format:
     example/foo/bar#frag
.fi
.IP --\fBstats\fP=enumeration
Controls YANG usage statistics report generation.
.nf
   enum values:
      none: (default)
         No statistics reporting will be done.
      brief:
        Brief statistics reporting will be done:
          - Complexity score
          - Total nodes
      basic:
         Basic statistics reporting will be done.
      advanced:
         Advanced statistics reporting will be done.
      all:
         All possible statistics reporting will be done.
.fi
.IP --\fBsubdirs\fP=boolean
If false, the file search paths for modules, scripts, and data
files will not include sub-directories if they exist in the
specified path.
      
If true, then these file search paths will include
sub-directories, if present.  Any directory name beginning
with a dot (\fB.\fP) character, or named \fBCVS\fP, will be ignored.
This is the default mode.
.IP --\fBsubtree\fP=string
Path specification of the directory subtree to convert.
All of the YANG and YIN source modules contained in the
specified directory sub-tree will be processed.

If the \fBformat\fP parameter is present, then one file
with the default name will be generated for each
YANG or YIN file found in the sub-tree.
        
Note that symbolic links are not followed
during the directory traversal.  Only real directories
will be searched and regular files will be checked as
modules.  Processing will continue to the next file
if a module contains errors.

If this string begins with a '~' character,
then a username is expected to follow or
a directory separator character.  If it begins
with a '$' character, then an environment variable
name is expected to follow.

This parameter may be present zero or more times.
.nf

      ~/some/path ==> <my-home-dir>/some/path

      ~fred/some/path ==> <fred-home-dir>/some/path

      $workdir/some/path ==> <workdir-env-var>/some/path
.fi
.IP --\fBtotals\fP=enumeration
Controls summary YANG usage statistics report generation.
Must be used with the '--stats' parameter.
.nf
   enum values:
      none: (default)
         No summary statistics reporting will be done.
      summary:
         Summary statistics totals will be 
         reported, based on the stats mode 
         that is requested.
      summary-only
         Only the summary statistics totals
         will be reported, based on the stats
         mode that is requested.  This mode
         will cause all individual module
         statistics reports to be generated,
         and a summary for all input modules
         will be generated instead.
.fi
.IP --\fBtree-identifiers\fP
Validate the file, write the hierarchy of node names
in tree format, that this [sub]module contains, then exit.
        
Each accessible object node is listed once,
including all child nodes.  Notifications and
RPC methods are considered top-level objects,
and have object identifiers as well as configuration
and state data..
.IP --\fBunified\fP=boolean
If true, then submodules will be processed within
the main module, in a unified report, 
instead of separately, one report for each file.

For translation purposes, this parameter will cause
any sub-modules to be treated as if they were defined in
the main module.  Actual definitions will be generated
instead of an 'include' directive, for each submodule.

If false (the default), then a separate output file is generated for each
input file, so that XSD output and other reports
for a main module will not include information for
submodules.

If this parameter is set to true, then submodules entered
with the \fBmodule\fP parameter will be ignored.
.IP --\fBurlstart\fP=string
If present, then this string will be used to prepend
to HREF links and URLs generated for SQL and HTML
translation.  It is expected to be a URL ending
with a directory path.  The trailing separator '/'
will be added if it is missing.

If not present (the default), then relative URLs,
starting with the file name will be generated instead.

For example, if this parameter is set to
.nf 

  'http://acme.com/public'

.fi
then the URL generated for the 'bar' type on line 53,
in the module FOO (version 2008-01-01) would be:
.nf

  if no-versionnames set:

    'http://acme.com/public/FOO.html#bar.53'  

   OR

  if no-versionnames not set (default):

   'http://acme.com/public/FOO_2008-01-01.html#bar.53' 

.fi
.IP --\fBversion\fP
Print yangdump version string and exit.
.IP --\fBversionnames\fP=boolean
If false, the default filenames will not contain
the module version string.  If true, the [sub]module
name and version string are both used to generate
a default file name, when the \fBdefnames\fP output parameter
is used.  This flag will cause filenames and links
to be generated which do not contain the version string.
The default value is true.
.IP --\fBwarn-idlen\fP=number
 Control whether identifier length warnings will be
generated.  The value zero disables all identifier
length checking.  If non-zero, then a warning will
be generated if an identifier is defined which 
has a length is greater than this amount.
range: 0 | 8 .. 1023.
The default value is 64.
.IP --\fBwarn-linelen\fP=number
Control whether line length warnings will be
generated.  The value zero disables all line length
checking.  If non-zero, then a warning will
be generated if the line length is greater than
this amount.  Tab characters are counted as 8 spaces.
range: 0 | 40 .. 4095.
The default value is 72.
.IP --\fBwarn-off\fP=number
Control whether the specified warning number will be
generated and counted in the warning total for the
module being parsed.
range: 400 .. 899.
This parameter may be entered zero or more times.
.IP --\fBxsd-schemaloc\fP=string
If present, then this string will be used to prepend
to output XSD filenames, when generating schemaLocation
clauses.  It is expected to be a URL ending
with a directory path.  The trailing separator '/'
will be added if it is missing.  This parameter
is also prepended to URLs generated fpr include and import
directives within the XSD. 

If not present (the default), then the schemaLocation
element is not generated during XSD translation.
Relative URLs for include and import directives will
be generated, starting with the file name.

For example, if this parameter is set to
.nf 

  'http://acme.com/public'

.fi
then the schemaLocation XSD for the module FOO 
(version 01-01-2008) would be:
.nf

   if no-versionnames set:

      'http://acme.com/public/FOO.xsd'  

  OR

   if no-versionnames not set (default):

      'http://acme.com/public/FOO_2008-01-01.xsd'
.fi
.IP --\fByuma-home\fP=string
Directory for the yuma project root to use.
If present, this directory location will
override the YUMA_HOME environment variable,
if it is present.  If a zero-length string is
entered, then the YUMA_HOME environment variable
will be ignored.

.SH INPUT FILES
Operations can be performed on one or more files with
the \fBmodule\fP parameter, or an entire directory tree
with the \fBsubtree\fP parameter.  Unless the \fBhelp\fP,
\fBversion\fP, or \fBshow-errors\fP parameters is entered, 
one of these input file parameters is mandatory.
Each of these parameters may be entered multiple times.
The default parameter for yangdump is 'module', so these
commands are wquivalent:
.nf

   yangdump --module=foo

   yangdump foo

.fi
Note that 'foo' must not match another parameter name.
If it does, the module parameter name must be used for that module.
For example,
.nf

   yangdump --module=help

.fi

.SH SEARCH PATH
When a module name is entered as input, or when a
module or submodule name is specified in an import or include
statement within the file, the following search algorithm
is used to find the file:
.nf    

  1) file is in the current directory
  2) YUMA_MODPATH environment var (or set by modpath parameter)
  3) $HOME/modules directory
  4) $YUMA_HOME/modules directory
  5) $YUMA_INSTALL/modules directory OR
     default install module location, '/usr/share/yuma/modules'

.fi
By default, the entire directory tree for all locations
(except step 1) will be searched, not just the specified
directory.  The \fBsubdirs\fP parameter can be used to
prevent sub-directories from being searched.
    
Any directory name beginning with a dot character (\fB.\fP)
will be skipped.  Also, any directory named \fBCVS\fP will
be skipped in directory searches.

.SH OUTPUT MODES
By default, any translation output will be sent to \fBSTDOUT\fP.
    
The \fBoutput\fP parameter can be used to specify the 
full filespec of the output file to use instead.
    
The \fBdefname\fP parameter can be used to generate a default
filename in the current directory for the output.
    
   E.g., the default XSD filename is \fB<name>_<version>.xsd\fP.
    
This is the default mode when \fBsubtree\fP input mode is selected.

.SH ERROR LOGGING
By default, warnings and errors are sent to STDOUT.
    
A log file can be specified instead with the \fBlog\fP' parameter.

Existing log files can be reused with the 'logappend'
parameter, otherwise log files are overwritten.
    
The logging level can be controlled with the \fBlog-level\fP
parameter.

The default log level is 'info'.  The
log-levels are additive:
.nf

     off:    suppress all errors (not recommended!)
             A program return code of '1' indicates some error.
     error:  print errors
     warn:   print warnings
     info:   print generally interesting trace info
     debug:  print general debugging trace info
     debug2: print verbose debugging trace info
     debug3: print very verbose debugging trace info
     debug4: print maximum debugging trace info

.fi

.SH ENVIRONMENT
The following optional environment variables can be used
to control module search behavior:

.IP \fBHOME\fP
The user's home directory  (e.g., /home/andy)
.IP \fBYUMA_HOME\fP
The root of the user's Yuma work directory
(e.g., /home/andy/swdev/netconf)
.IP \fBYUMA_INSTALL\fP
The root of the directory that yangdump
is installed on this system (default is, /usr/share/yuma)
.IP \fBYUMA_MODPATH\fP
Colon-separated list of directories to
search for modules and submodules.

(e.g.: './workdir/modules:/home/andy/test-modules')

The \fBmodpath\fP parameter will override this
environment variable, if both are present.

.SH CONFIGURATION FILES
.IP \fByangdump.conf\fP
YANG config file
The default is: \fB/etc/yuma/yangdump.conf\fP
    
An ASCII configuration file format is supported to
store command line parameters. 

The \fBconfig\fP parameter
is used to specify a specific config file, otherwise
the default config file will be checked.
.nf    

   - A hash mark until EOLN is treated as a comment
   - All text is case-sensitive
   - Whitespace within a line is not significant
   - Whitespace to end a line is significant/
     Unless the line starts a multi-line string,
     an escaped EOLN (backslash EOLN) is needed
     to enter a leaf on multiple lines.
   - For parameters that define lists, the key components
     are listed just after the parameter name, without
     any name,  e.g.,
    
            interface eth0 {
              # name = eth0 is not listed inside the braces
              ifMtu 1500
              ifName mySystem
            }

.fi    
A config file can contain any number of parameter
sets for different programs. 

Each program must have its own section, identifies by its name:
.nf    

     # this is a comment
     yangdump {
        log-level debug
        output "~/swdev/testfiles"
     }
    
     netconfd {
        ...
     }

.fi

.SH FILES
The following data files must be present in the module
search path in order for this program to function:
    
  * \fBYANG module library\fP
    default: /usr/share/yuma/modules/
    

.SH DIAGNOSTICS
Internal diagnostics may generate the following
type of message if any bugs are detected at runtime:
.nf
  
    [E0]
         filename.c:linenum error-number (error-msg)

.fi
.SH AUTHOR
Andy Bierman, <andy at netconfcentral dot org>

.SH SEE ALSO
.BR netconfd (1)
.BR yangcli (1)
.BR yangdiff (1)
